---
title: 人間の介入（HITL）
description: Add a human in the loop check for your agent executions
---

import { Aside, Code } from '@astrojs/starlight/components';
import humanInTheLoopExample from '../../../../../../examples/docs/human-in-the-loop/index.ts?raw';
import toolApprovalDefinition from '../../../../../../examples/docs/human-in-the-loop/toolApprovalDefinition.ts?raw';

このガイドでは、SDK に組み込まれた Human in the loop (人間の介入) のサポートを使用して、人間の介入に基づきエージェントの実行を一時停止・再開する方法を説明します。

現在の主なユースケースは、機微なツール実行に対する承認を求めることです。

## 承認リクエスト

`needsApproval` オプションを `true`、または boolean を返す非同期関数に設定することで、承認が必要なツールを定義できます。

<Code
  lang="typescript"
  code={toolApprovalDefinition}
  title="ツール承認の定義"
  meta={`{10}`}
/>

### フロー

1. エージェントがツール（複数含む）を呼び出す判断をした場合、`needsApproval` を評価してそのツールに承認が必要かどうかを確認します
2. 承認が必要な場合、エージェントは承認がすでに許可または拒否されているかを確認します
   - 承認が許可または拒否されていない場合、ツールは「ツール呼び出しを実行できない」という固定メッセージをエージェントに返します
   - 承認／拒否が未処理であれば、ツール承認リクエストがトリガーされます
3. エージェントはすべてのツール承認リクエストを収集し、実行を中断します
4. 中断がある場合、[エージェントの実行結果](/openai-agents-js/ja/guides/results) に保留中のステップを表す `interruptions` 配列が含まれます。ツール呼び出しに確認が必要な場合は、`type: "tool_approval_item"` の `ToolApprovalItem` が現れます
5. ツール呼び出しを承認または拒否するには、`result.state.approve(interruption)` または `result.state.reject(interruption)` を呼び出します
6. すべての中断を処理したら、`result.state` を `runner.run(agent, state)` に渡して実行を再開できます。ここで `agent` は全体の実行をトリガーした元のエージェントです
7. フローはステップ 1 から再開します

## 例

以下は、ターミナルで承認を促し、状態を一時的にファイルへ保存する Human in the loop (人間の介入) フローの、より完全な例です。

<Code
  lang="typescript"
  code={humanInTheLoopExample}
  title="Human in the loop (人間の介入)"
/>

エンドツーエンドで動作する版は [the full example script](https://github.com/openai/openai-agents-js/tree/main/examples/agent-patterns/human-in-the-loop.ts) を参照してください。

## 長時間の承認への対応

Human in the loop (人間の介入) のフローは、サーバーを起動し続けることなく、長時間の中断に耐えられるよう設計されています。リクエストをいったん終了し、後で続行する必要がある場合は、状態をシリアライズして後から再開できます。

状態は `JSON.stringify(result.state)` でシリアライズでき、後でシリアライズ済みの状態を `RunState.fromString(agent, serializedState)` に渡すことで再開できます。ここで `agent` は全体の実行をトリガーしたエージェントのインスタンスです。

この方法により、シリアライズ済みの状態をデータベースやリクエストと一緒に保存できます。

### 保留中タスクのバージョニング

<Aside>
  これは主に、エージェントに変更を加えつつ、シリアライズ済みの状態を
  長期間保存しようとしている場合に該当します。
</Aside>

承認リクエストに長時間かかり、エージェント定義に意味のある形でバージョン管理を行いたい、または Agents SDK のバージョンを更新したい場合は、パッケージエイリアスを使って 2 つの Agents SDK バージョンを並行インストールし、独自のブランチロジックを実装することを現在は推奨します。

実務的には、独自のコードにバージョン番号を割り当て、シリアライズ済み状態と一緒に保存し、デシリアライズをコードの正しいバージョンへ誘導することを意味します。
